Skip to main content

Create Testnet iteratively

So, you've decided to use Harbor to get your hands dirty with Testnets. How do you start creating your Testnets?

In this section, you will learn to build your Testnets iteratively. You will be shown how to build your Testnet, piece by piece, by adding one actor at a time.

Quickstart​

At Harbor, you can quickly get started with a sample Testnet that contains one ethereum chain in one command.

harbor quickstart <quickstart-name>

This will give you the log:

🌍 Testnet create/update in progress...  [1m59s]

Until the Testnet runs. When it's done running, you should see:

Status = ✔ RUNNING
Chain = ⛓️ethereum
Endpoint = 🌎 http://65.2.132.188:4000

Total chains count: 1

Total off-chain actors count: 0

Use the endpoint to interact with your actor(s).

Let's say this running Testnet name is called example-testnet, and you'd like to add more to it, piece by piece. How do you do that?

Harbor has commands that will easily let you add and remove actors (both chains and off-chain actors).

Adding an actor​

The add command is:

harbor edit example-testnet add <actor-name> <additional-flags> --tag example-tag

The tag flag is mandatory.

Depending on the <actor-name>, you end up either adding a chain or adding an off-chain actor.

You must use additional flags if it is either an off-chain actor or a chain to successfully add. Otherwise, the command will fail.

Adding chains​

To add a chain, the <chain-name> has to be a recognized chain in Harbor. Here is a list of names recognized as chains:

You also need to provide the following flags:

  • artifacts-path the path to your compiled contracts directory
  • deploy-path the path to your deploy scripts directory
  • tag the string that identifies the current version of the actor

So, if you wanted to add polygon, you just run:

harbor edit example-testnet add polygon --artifacts-path /path/to/artifacts/ --deploy-path /path/to/deploy/ --tag polygon-tag

Adding the tag flag is mandatory. This will give us:

🌍 Testnet create/update in progress...  [1m59s]

This is also reflected in the UI through the Updating status on the Testnet:

update_testnet

Then, after some time, the Testnet should say Running again:

running_testnet

This means that the Testnet has been successfully updated with the new chain.

Adding a chain with wallets​

Adding a chain with wallets follows the same command from above, but with three additional flags:

  • wallet the number of wallets
  • token the symbol(s) of tokens needed
  • amount the number of tokens, respectively according to the order of the token symbols provided.

Let's say we wanted to add an ethereum chain that has 3 wallets containing 2000 dai each. For this, we run the command:

harbor edit <testnet-name> add ethereum --wallet 3 --token dai --amount 2000 <additional-flags> --tag tokens

What if we wanted to add both dai and matic at 2000 and 5000 each (respectively)? Not a problem! For that, we run:

harbor edit <testnet-name> add ethereum --wallet 3 --token dai,matic --amount 2000,5000 <additional-flags> --tag tokens

Or, we can also update our ethereum chain to add these wallets:

harbor edit <testnet-name> update ethereum --wallet 3 --token dai,matic --amount 2000,5000 <additional-flags> --tag tokens

Either command we run, we will see:

Chains to be added: [ethereum]
Configuring chain ethereum
🌎 Testnet create/update in progress...  [1m34s]

Until the Testnet is fully updated:

##### 1 Chains

Chain = ⛓ ethereum
Status = ✔️ RUNNING
Endpoint = 🌎 http://13.127.195.221:4000

###### 0 Off-chain actors

Adding off-chain actors​

To add an off-chain actor, you need to make sure that the <actor-name> is not the name of a chain. If the name is a chain, then it will be automatically added as a chain. You also need to provide either:

  • image flag if it's a public image actor OR

  • docker-file and build-path flags if it's a local actor

  • tag the string that identifies the current version of the off-chain actor

    • If we are updating the off-chain actor, then we must add a new tag value and run harbor apply <testnet-name>

    • Only + - = . _ : / @ are allowed as special characters

Failing to do so will result in an error.

So, if you run:

harbor edit example-testnet add liquidationBot --image liquidationBot --tag liquidationBot-tag

Or:

harbor edit example-testnet add liquidationBot --docker-file /path/to/dockerfile --build-path /path/to/build --tag liquidation-tag

Then the Testnet will update with the postgres off-chain actor by showing:

Off-chain actors to be added: [liquidationBot]
Configuring off-chain actor liquidationBot
🌎 Testnet create/update in progress...  [1m34s]

This is also reflected in the UI through the Updating status on the Testnet:

update_testnet

Then, after some time, the Testnet should say RUNNING:

###### 1 Chains

Chain = ⛓ ethereum
Status = ✔️ RUNNING
Endpoint = 🌎 http://13.127.195.221:4000

###### 1 Off-chain actors

Off-chain Actor = liquidationBot
Status = ✔ RUNNING
Endpoint = 🌎 http://13.233.108.183:8080

running_testnet

This means that the Testnet has been successfully updated with the new off-chain actor. Remember that the tag flags are mandatory for these commands.

Flags you can use​

  • build-path The build path to be used with docker file for the off-chain actor
  • command The command to be used for the off-chain actor
    • Example: if we have a postgres off-chain actor in a Testnet, we can add this command to its configuration:
    "command": "postgres -cshared_preload_libraries=pg_stat_statements"
  • depends-on Dependencies for the chain or off-chain actor
  • deploy-path The path to the chain's smart contract deploy folder
  • docker-file The docker file for the off-chain actor
  • env Environment variables to be set (default [])
  • image Image to be used for the off-chain actor
  • include-paths The paths to be included while building the chain
  • ports The ports that must be opened for the off-chain actor
  • schedule-exp The rate schedule expression for the off-chain actor which determines the frequency with which the actor has to be invoked
    • i.e: rate (1 minute) as a value of schedule-exp means that the off-chain actor is invoked every 1 minute
    • Set the expression for how often an off-chain actor should run
  • tag the string that identifies the current version of the actor
    • Track updates on your off-chain actors and chains. If the off-chain actor or chain is different from what is already running on the Testnet, then we must update the tag string and run harbor apply <testnet-name>>

Removing an actor​

To remove a chain or an off-chain actor, you can run the following command:

harbor edit <testnet-name> remove <actor-name>

Where the <testnet-name> is the name of the Testnet and the <actor-name> is the name of the actor.